Skip to content

Adopt OTel semantic conventions for agents and frameworks #2575

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Adopt OTel semantic conventions for agents and frameworks #2575

wants to merge 1 commit into from
+85 −13

Conversation

krisztianfekete
Copy link

@krisztianfekete krisztianfekete commented Aug 16, 2025 •
edited
Loading

This PR adopts the current OpenTelemetry Semantic Conventions for genAI agents and frameworks as per https://opentelemetry.io/docs/specs/semconv/gen-ai/gen-ai-agent-spans/

Fixes #1826

Sets

Adds missing attributes:

  • gen_ai.operation.name
  • gen_ai.response.model
  • gen_ai.request.temperature

Adds new utility functions to support proper OpenTelemetry conventions for naming and event emission:

  • _create_span_name(operation_name: str, model_name: str) -> str
    Creates span names following the OTel convention: {operation_name} {model_name}

  • add_genai_prompt_event(span: trace.Span, prompt_content: str)
    Adds GenAI prompt events using the standard gen_ai.content.prompt event name

  • add_genai_completion_event(span: trace.Span, completion_content: str)
    Adds GenAI completion events using the standard gen_ai.content.completion event name

Local demo script:

1. Testing LLM call tracing...
{
    "name": "demo_llm_call",
    "context": {
        "trace_id": "0xe78adcbecdf985c1c7c262c3c33db577",
        "span_id": "0xe6ed7db0560f26e9",
        "trace_state": "[]"
    },
    "kind": "SpanKind.INTERNAL",
    "parent_id": null,
    "start_time": "2025-08-16T09:30:19.056838Z",
    "end_time": "2025-08-16T09:30:19.057007Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.system": "gcp.vertex_ai",
        "gen_ai.operation.name": "generate_content",
        "gen_ai.request.model": "gemini-1.5-pro",
        "gcp.vertex.agent.invocation_id": "demo_invocation",
        "gcp.vertex.agent.session_id": "0c31b27b-ecdf-4907-b7b4-0434735b950a",
        "gcp.vertex.agent.event_id": "demo_event_1",
        "gcp.vertex.agent.llm_request": "{\"model\": \"gemini-1.5-pro\", \"config\": {\"temperature\": 0.7, \"top_p\": 0.9, \"max_output_tokens\": 100}, \"contents\": [{\"parts\": [{\"text\": \"Hello!\"}], \"role\": \"user\"}]}",
        "gen_ai.request.top_p": 0.9,
        "gen_ai.request.max_tokens": 100,
        "gen_ai.request.temperature": 0.7,
        "gcp.vertex.agent.llm_response": "{\"turn_complete\":true,\"finish_reason\":\"STOP\",\"usage_metadata\":{\"candidates_token_count\":25,\"prompt_token_count\":10,\"total_token_count\":35}}",
        "gen_ai.usage.input_tokens": 10,
        "gen_ai.usage.output_tokens": 25,
        "gen_ai.response.finish_reasons": [
            "stop"
        ]
    },
    "events": [
        {
            "name": "gen_ai.content.prompt",
            "timestamp": "2025-08-16T09:30:19.056936Z",
            "attributes": {
                "gen_ai.prompt": "{\"role\": \"user\", \"content\": \"Hello!\"}"
            }
        },
        {
            "name": "gen_ai.content.completion",
            "timestamp": "2025-08-16T09:30:19.056940Z",
            "attributes": {
                "gen_ai.completion": "{\"role\": \"assistant\", \"content\": \"Hi there!\"}"
            }
        }
    ],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.36.0",
            "service.name": "unknown_service"
        },
        "schema_url": ""
    }
}

==================================================

2. Testing tool call tracing...
{
    "name": "demo_tool_call",
    "context": {
        "trace_id": "0x26cfb72b4a7f9394b14752acc7d9a692",
        "span_id": "0xba6692531c76da81",
        "trace_state": "[]"
    },
    "kind": "SpanKind.INTERNAL",
    "parent_id": null,
    "start_time": "2025-08-16T09:30:19.057252Z",
    "end_time": "2025-08-16T09:30:19.057288Z",
    "status": {
        "status_code": "UNSET"
    },
    "attributes": {
        "gen_ai.system": "gcp.vertex_ai",
        "gen_ai.operation.name": "execute_tool",
        "gen_ai.tool.name": "demo_tool",
        "gen_ai.tool.description": "A demo tool for testing",
        "gen_ai.tool.call.id": "tool_call_123",
        "gcp.vertex.agent.tool_call_args": "{\"param1\": \"value1\", \"param2\": 42}",
        "gcp.vertex.agent.event_id": "demo_tool_event",
        "gcp.vertex.agent.tool_response": "{\"result\": \"Tool executed successfully\"}",
        "gcp.vertex.agent.llm_request": "{}",
        "gcp.vertex.agent.llm_response": "{}"
    },
    "events": [],
    "links": [],
    "resource": {
        "attributes": {
            "telemetry.sdk.language": "python",
            "telemetry.sdk.name": "opentelemetry",
            "telemetry.sdk.version": "1.36.0",
            "service.name": "unknown_service"
        },
        "schema_url": ""
    }
}

@google-cla Google CLA
Copy link

google-cla bot commented Aug 16, 2025

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

@adk-bot adk-bot added bot triaged [Bot] This issue is triaged by ADK bot tracing [Component] This issue is related to OpenTelemetry tracing labels Aug 16, 2025
@adk-bot
Copy link
Collaborator

adk-bot commented Aug 16, 2025

Response from ADK Triaging Agent

Hello @krisztianfekete, thank you for your contribution!

It looks like a couple of automated checks are failing on this PR. To help move this forward, could you please address the following?

  • Commit Message Format: The conventionalcommits.org check is failing. Please ensure your commit message and PR title follow the Conventional Commits specification as outlined in our contribution guidelines.
  • Contributor License Agreement (CLA): The cla/google check has failed. Please ensure you have signed the CLA, as this is a requirement for merging contributions. The google-cla bot has provided instructions in an earlier comment.

Addressing these items will help our reviewers proceed with the review process. Thanks!

@adk-bot adk-bot requested a review from Jacksunwei August 16, 2025 09:32
@krisztianfekete krisztianfekete changed the title Adopt OTel semantic conventions for agents and frameworks adopt OTel semantic conventions for agents and frameworks Aug 16, 2025
@krisztianfekete krisztianfekete changed the title adopt OTel semantic conventions for agents and frameworks Adopt OTel semantic conventions for agents and frameworks Aug 16, 2025
@krisztianfekete
feat: adopt OpenTelemetry semantic conventions for GenAI agents and f…
e5ef820 
…rameworks

- Fix gen_ai.system value to use 'gcp.vertex_ai' instead of 'gcp.vertex.agent'
- Move custom attributes to gcp.vertex.agent.* vendor-specific namespace
- Add missing standard GenAI attributes (response.id, response.model, request.temperature)
- Add gen_ai.operation.name for all operations (generate_content, execute_tool)
- Update gen_ai.response.finish_reasons to use array format
- Add utility functions for GenAI events and span naming
- Update tests and web server to use new attribute names

Aligns with OpenTelemetry GenAI semantic conventions v1.36.0
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@Jacksunwei Jacksunwei Awaiting requested review from Jacksunwei

At least 1 approving review is required to merge this pull request.

Assignees
No one assigned
Labels
bot triaged [Bot] This issue is triaged by ADK bot tracing [Component] This issue is related to OpenTelemetry tracing
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

Need support standard gen_ai span attributions
2 participants
@krisztianfekete @adk-bot